/// <summary>
/// Returns the first <see cref="Rock.Model.Location" /> where the address matches the provided address, otherwise the address will be saved as a new location.
/// Note: The location search IS NOT constrained by the provided group. Providing the group will cause this method to search that groups locations first, giving a faster result.
/// </summary>
/// <param name="street1">A <see cref="string" /> representing the Address Line 1 to search by.</param>
/// <param name="street2">A <see cref="string" /> representing the Address Line 2 to search by.</param>
/// <param name="city">A <see cref="string" /> representing the City to search by.</param>
/// <param name="state">A <see cref="string" /> representing the State/Province to search by.</param>
/// <param name="locality">A <see cref="string" /> representing the Locality/County to search by</param>
/// <param name="postalCode">A <see cref="string" /> representing the Zip/Postal code to search by</param>
/// <param name="country">A <see cref="string" /> representing the Country to search by</param>
/// <param name="group">The <see cref="Group"/> (usually a Family) that should be searched first. This is NOT a search constraint.</param>
/// <param name="verifyLocation">if set to <c>true</c> [verify location].</param>
/// <param name="createNewLocation">if set to <c>true</c> a new location will be created if it does not exists.</param>
/// <returns>
/// The first <see cref="Rock.Model.Location" /> where an address match is found, if no match is found a new <see cref="Rock.Model.Location" /> is created and returned.
/// </returns>
public Location Get(string street1, string street2, string city, string state, string locality, string postalCode, string country, Group group, bool verifyLocation = true, bool createNewLocation = true)
{
GetLocationArgs getLocationArgs = new GetLocationArgs
{
Group = group,
VerifyLocation = verifyLocation,
CreateNewLocation = createNewLocation,
};
return(Get(street1, street2, city, state, locality, postalCode, country, getLocationArgs));
}
/// <summary>
/// Returns the first <see cref="Rock.Model.Location" /> where the address matches the provided address, otherwise the address will be saved as a new location.
/// Note: The location search IS NOT constrained by the provided <seealso cref="GetLocationArgs.Group"></seealso>. Providing the group will cause this method to search that groups locations first, giving a faster result.
/// </summary>
/// <param name="street1">A <see cref="string" /> representing the Address Line 1 to search by.</param>
/// <param name="street2">A <see cref="string" /> representing the Address Line 2 to search by.</param>
/// <param name="city">A <see cref="string" /> representing the City to search by.</param>
/// <param name="state">A <see cref="string" /> representing the State/Province to search by.</param>
/// <param name="locality">A <see cref="string" /> representing the Locality/County to search by</param>
/// <param name="postalCode">A <see cref="string" /> representing the Zip/Postal code to search by</param>
/// <param name="country">A <see cref="string" /> representing the Country to search by</param>
/// <param name="getLocationArgs">The <seealso cref="GetLocationArgs"/></param>
/// <returns>
/// The first <see cref="Rock.Model.Location" /> where an address match is found, if no match is found a new <see cref="Rock.Model.Location" /> is created and returned.
/// </returns>
/// <exception cref="System.Exception"></exception>
public Location Get(string street1, string street2, string city, string state, string locality, string postalCode, string country, GetLocationArgs getLocationArgs)
{
Group group = getLocationArgs?.Group;
bool verifyLocation = getLocationArgs?.VerifyLocation ?? true;
bool createNewLocation = getLocationArgs?.CreateNewLocation ?? true;
var validateLocation = getLocationArgs?.ValidateLocation ?? true;
// Remove leading and trailing whitespace.
street1 = street1.ToStringSafe().Trim();
street2 = street2.ToStringSafe().Trim();
city = city.ToStringSafe().Trim();
state = state.ToStringSafe().Trim();
locality = locality.ToStringSafe().Trim();
postalCode = postalCode.ToStringSafe().Trim();
country = country.ToStringSafe().Trim();
// Make sure the address has some content.
if (string.IsNullOrWhiteSpace(street1) &&
string.IsNullOrWhiteSpace(street2) &&
string.IsNullOrWhiteSpace(city) &&
string.IsNullOrWhiteSpace(state) &&
string.IsNullOrWhiteSpace(locality) &&
string.IsNullOrWhiteSpace(postalCode) &&
string.IsNullOrWhiteSpace(country))
{
return(null);
}
// Try to find a location that matches the values, this is not a case sensitive match
var foundLocation = Search(new Location {
Street1 = street1, Street2 = street2, City = city, State = state, County = locality, PostalCode = postalCode, Country = country
}, group);
if (foundLocation != null)
{
// Check for casing
if (!String.Equals(street1, foundLocation.Street1) || !String.Equals(street2, foundLocation.Street2) || !String.Equals(city, foundLocation.City) || !String.Equals(state, foundLocation.State) || !String.Equals(postalCode, foundLocation.PostalCode) || !String.Equals(country, foundLocation.Country))
{
var context = new RockContext();
var location = new LocationService(context).Get(foundLocation.Id);
location.Street1 = street1;
location.Street2 = street2;
location.City = city;
location.State = state;
location.County = locality;
location.PostalCode = postalCode;
location.Country = country;
context.SaveChanges();
return(Get(location.Guid));
}
return(foundLocation);
}
// If existing location wasn't found with entered values, try standardizing the values, and search for an existing value again
var newLocation = new Location
{
Street1 = street1.FixCase(),
Street2 = street2.FixCase(),
City = city.FixCase(),
State = state,
County = locality,
PostalCode = postalCode,
Country = country
};
if (verifyLocation)
{
Verify(newLocation, false);
}
foundLocation = Search(newLocation, group);
if (foundLocation != null)
{
return(foundLocation);
}
if (createNewLocation)
{
if (validateLocation)
{
// Verify that the new location has all of the required fields.
string validationError;
var isValid = ValidateAddressRequirements(newLocation, out validationError);
if (!isValid)
{
throw new Exception(validationError);
}
}
// Create a new context/service so that save does not affect calling method's context
var rockContext = new RockContext();
var locationService = new LocationService(rockContext);
locationService.Add(newLocation);
rockContext.SaveChanges();
}
// refetch it from the database to make sure we get a valid .Id
return(Get(newLocation.Guid));
}
/// <summary>
/// Returns the first <see cref="Rock.Model.Location" /> where the address matches the provided address, otherwise the address will be saved as a new location.
/// Note: The location search IS NOT constrained by the provided <seealso cref="GetLocationArgs.Group"></seealso>. Providing the group will cause this method to search that groups locations first, giving a faster result.
/// </summary>
/// <param name="street1">A <see cref="string" /> representing the Address Line 1 to search by.</param>
/// <param name="street2">A <see cref="string" /> representing the Address Line 2 to search by.</param>
/// <param name="city">A <see cref="string" /> representing the City to search by.</param>
/// <param name="state">A <see cref="string" /> representing the State/Province to search by.</param>
/// <param name="postalCode">A <see cref="string" /> representing the Zip/Postal code to search by</param>
/// <param name="country">A <see cref="string" /> representing the Country to search by</param>
/// <param name="getLocationArgs">The <seealso cref="GetLocationArgs"/></param>
/// <returns>
/// The first <see cref="Rock.Model.Location" /> where an address match is found, if no match is found a new <see cref="Rock.Model.Location" /> is created and returned.
/// </returns>
/// <exception cref="System.Exception"></exception>
public Location Get(string street1, string street2, string city, string state, string postalCode, string country, GetLocationArgs getLocationArgs)
{
string locality = null;
return(Get(street1, street2, city, state, locality, postalCode, country, getLocationArgs));
}
